XML Instance Quick Tour

Welcome

To help you become familiar with XML Instance^tm we have included this step-by-step exercise to create an XML document . This exercise will teach you how to navigate the product and  introduce you to the fundamental features of  XML Instance. This exercise should take around 15 minutes to complete. For more information about XML Instance, consult the Help Index.

The Example

XML Instance is a "schema-aware" editor which means you can validate your XML documents against a DTD or schema (e.g. XDR, SOX, XSDL) as you build them or after they have been created.  In our example, we will create an XML document using a schema as a template and will demonstrate the customizable view you can create of that document as well as all documents you later create based on the same schema.

Getting Started

• Launch XML Instance.  From the Welcome Screen (fig.1), select "Create Document".

Fig. 1- Welcome Screen.

This will open the application and default to a new XML document with just the root element showing.  If you wanted to create a new document without the use of a schema, you could simply rename (right-click>rename) the root element to a tag name of your choice and then build your document from there.  In our example, however, we are going to create this document based on a schema for an XML document containing information about users and groups that could be used to configure an application. 

• Click "Set Schema" from the toolbar at the top of the screen and browse to identify the schema you would like to use.  We have provided the quicktour.xsd file for you to use in the samples folder. (Extensibility\XI\Samples\quicktour.xsd)

• After setting the schema, you will notice the elements and attributes declared in the schema now show up in the tag area on the left side of the user interface.  Additionally, the structure of the document as defined by the schema is visible as content hints viewable in the edit area. (See fig. 2)

Fig. 2 Content hints represented in the edit area.

The content hints give you an indication of how the elements of the schema are structured and what additional elements are valid in a conforming XML document.  In the diagram above, you can see that user+ is a repeatable element within the content model of userList. 

Customizing and Building Your Document

Now we will customize the view we have of this document to make it more approachable and facilitate the entry of data within it.  The view we create of this document by using the features of XML Instance  will be preserved and associated with the schema used to create this document. This means that as long as needed, every new XML document created using the same schema will be presented the same way automatically.

• If you right-click (or control-click with a one button mouse) on the element groupName underneath the element group you will be given some contextual choices.  Select Element Type "groupName">Color>Green to highlight the element with a green background. (see fig.3)

Fig. 3 Coloring elements by tag name.

You will notice that each groupName element has now been highlighted in green.  This makes finding the element to add data or content easy and identifies each occurrence of the element. 

• Next to the element groupName in this location, type in the word "Administrators" to identify this group by name.  

• To create a new group, click once on the element tag name group above groupName.  Now look at the factory bar at the bottom of the screen; you will see that <group> is visible to the right of the insert button. This element is available to be inserted because the content model of the root element groupList specified by the schema we are using allows group to be repeated.  Click the group button on the factory bar once to add a new group.

 The factory bar is one way you can insert new elements or attributes into your document;  you can also double-click an element and a drop-down window will appear for adding new components to your document (see figure below). This same window will appear if you hold the CTRL key down and press enter when an element is highlighted.  Once the window has appeared, you can use CTRL left-arrow and CTRL right- arrow to determine the position of your new element in relationship to the surrounding elements.  For example, aligning it with the element above will make it a sibling to that element, indenting it to the right will make it a child element.  Selecting the appropriate button in the drop down box will also determine the type of item you add to your document.

Note:  The factory bar will show elements and attributes that are valid within the document as specified by the governing schema. If you insert elements or attributes in the drop-down box, you can insert anything you want,  even if they are not valid.  You will receive a warning when you check your documents for errors that the element is invalid. 

Fig. 4 Inserting components into your document.

The factory bar is an easy way to build your valid XML documents.  The view of these elements and their child elements as well as attributes is highly configurable within XML Instance.  Now we will create some users for our example document and use this opportunity to show you these configurable qualities.

• To facilitate the adding of users, we will first give the element user a background color of yellow by right-clicking that element and selecting Element Type "user">Color>Yellow

• Now you can promote the child elements as well as the attributes of user to make the entry of data easier and the document view more manageable.  To do this, move your pointer over the small blue icon next to the attribute userNumber and drag this attribute to the right into the edit area and move it up one row.  There will be a small black indicator that will demonstrate where the attribute is going to be repositioned.  Release the attribute next to its associated element user. 

• Now drag the element userName up next to userNumber on the same level as its parent element user.

• Drag password up next to userName and  fullName up next to password.  You may need to resize these newly created columns in the edit area in order to add additional ones.

• Finally, drag email up next to fullName.  Your view should now look like Fig.4.

Fig. 4 Promoted elements.

Note:  Promoting the elements does not change their structural position within the XML document, just their position within the viewable interface of XML Instance.

• To illustrate the entry of data, enter an employee number (must be a valid integer based on the data type specified by the schema), your name, a password, full name, and email address within the fields adjacent to these elements.

• To enter your next users, create additional user fields by clicking the <user> button on the factory bar two or three more times and enter account information for each if you like.

To make your document more compact in its representation in XML Instance, you can select elements to be hidden from view.  If you are concerned only with the users in our example and not with group permissions or rights, you could hide those elements from view.

• Highlight the element permissions and then from the Type menu at the top of your screen, select Hide.  Repeat this for the element rights.

You will notice that these elements are now hidden everywhere that they occur in the document.  You can hide them in one place at a time by using the Item>Hide instead of the Type>Hide.  Keep in mind that these elements are not removed from the document by hiding, only from your view.  To reveal the hidden elements you can  highlight the parent element and select Item>Show All or Show.  To reveal all hidden elements or attributes, select the root element of the document and click Item>Show All. (Fig. 5 shows the completed document)

Fig 5 The Completed Example.

Congratulations! You have completed the quick tour example for customizing and building an XML document from a schema. 

One important feature of XML Instance is that once you create a document based on a schema, each additional document you make that uses the same schema will have the same view within XML Instance.  To test this, save your document and then start a new document and set the same quicktour.xsd to start it.  Immediately upon setting the schema, the view of the new document will be the same as this document.  (Note: to remove the preset view of a document, remove the corresponding schemaname.fileextension.xip file from the Extensibility\XI\presentation directory created during the installation of XML Instance; in this case the file name would be quicktour.xsd.xip)  The benefits of a consistent and customizable view for an entire class of documents can be numerous depending on how those documents are created and used.

This quick tour example was designed to introduce the user to some of the major features of XML Instance.  XML Instance has numerous other features detailed  in the help files.

To see all available help documents, please visit the help index; the documents identified there are a good source of information not only about how to use XML Instance but also about XML and schemas.

Thank you for choosing XML Instance from Extensibility.

If you have any questions please contact us at support@extensibility.com

Copyright 2000 Extensibility, Inc.

Suite 250, 200 Franklin Street, Chapel Hill, North Carolina 27516